/******************************************************************************
 * @file rd0ff_bsp_key_handler.h
 * @brief KEY处理器头文件
 *
 * 详细描述：
 * - 功能1：提供KEY驱动的高层封装与管理接口
 * - 功能2：实现KEY数据采集、处理与事件分发机制
 * - 功能3：集成操作系统队列通信与线程管理功能
 * - 功能4：提供错误处理与状态监控能力
 *
 * @author 陈泳行 | R&D Dept. | Jin Dou Aerospace 金斗航天
 * @date 2025-6-29
 * @version 1.0.0
 *
 * @version_history
 * - 1.0.0 (2025-6-29): 初始版本，实现基本功能
 *
 * @note 本模块依赖KEY驱动层和操作系统环境
 * @warning 处理器初始化前必须确保KEY驱动已完成初始化
 ******************************************************************************/
#ifndef __RD0FF_BSP_KEY_HANDLER_H
#define __RD0FF_BSP_KEY_HANDLER_H

/******************************** Includes ***********************************/
#include "rd0ff_bsp_key_driver.h"
/******************************** Includes ***********************************/

/******************************** Defines  ***********************************/
/**
 * @brief 操作系统支持宏定义
 *
 * 条件编译控制：
 * - 定义OS_SUPPIRTING_KEY：启用操作系统相关接口（如队列、线程）
 * - 未定义OS_SUPPIRTING_KEY：使用裸机环境实现（需用户提供基础接口）
 *
 * @note 由项目配置自动生成，用户无需手动修改
 */
#define OS_SUPPIRTING_KEY
/**
 * @brief KEY寄存器初始值
 *
 * 定义KEY驱动寄存器的初始校验值，用于驱动有效性检测
 */
#define KEY_REGISTER_INIT (bsp_key_driver_t *)(0xA6A6A6A6)
/******************************** Defines  ***********************************/

/******************************** Declare ************************************/
/**
 * @brief KEY操作返回状态码枚举
 *
 * 此枚举定义了KEY驱动所有操作可能返回的状态码，用于错误处理和调试。
 */
typedef enum
{
    KEY_HANDLER_RET_OK,
    KEY_HANDLER_RET_ERROR,
}key_handler_ret_t;

/**
 * @brief KEY初始化状态枚举
 *
 * 定义KEY外设的初始化和运行状态，用于状态管理。
 */
typedef enum
{
    KEY_HANDLER_INIT 	= 1, // 表示KEY已初始化。
    KEY_HANDLER_NO_INIT = 0, // 表示KEY未初始化。
} key_handler_init_t;

/**
 * @brief KEY按键索引枚举
 *
 * 定义系统支持的按键索引，用于按键识别和管理。
 */
typedef enum
{
    KEY1 = 0,
    KEY2,
    KEY3,
    KEY4,
    KEY5,
    KEY6,
	KEY_REGISTER_MAX,// 表示KEY的最大数量。
	KEY_HANDLER_NOT = 0xFFFFFF,// 表示KEY不存在。
}key_index_t;

/**
 * @brief KEY按键状态枚举
 *
 * 定义按键的物理状态（按下/释放），用于状态检测。
 */
typedef enum
{
    KEY_DOWN = 1,
    KEY_UP,
} key_status_t;

/**
 * @brief KEY按键类型枚举
 *
 * 定义按键事件类型（短按/长按/连击），用于事件处理。
 */
typedef enum
{
    KEY_INVALID = 0, // 无效
    KEY_SHORT,
    KEY_LONG,
    KEY_DOUBLE,  // 连击
} key_type_t;

/**
 * @brief KEY设备操作结构体
 *
 * 封装KEY外设的初始化、去初始化、启动和停止等操作函数，
 * 以及设备句柄和初始化状态。
 */
typedef struct 
{
    key_status_t status;         // 按键状态
    key_type_t type;             // 按键类型
    uint32_t press_time;         // 按下时长
    uint32_t release_time;       // 释放时长
    uint16_t double_max_time;    // 连击最大时长
    uint16_t short_min_time;     // 短按最小时长
    uint16_t double_count;       // 连击次数
    uint32_t long_min_time;      // 长按最小时长
    key_index_t index;   		 // 按键索引
} key_event_t;

/**
 * @brief KEY设备操作结构体
 *
 * 封装KEY外设的初始化、去初始化、启动和停止等操作函数，
 * 以及设备句柄和初始化状态。
 */
typedef struct
{
    uint32_t                                     key_num;
    bsp_key_driver_t *pa_register_group[KEY_REGISTER_MAX];
} key_register_t;

/**
 * @brief KEY设备操作结构体
 *
 * 封装KEY外设的初始化、去初始化、启动和停止等操作函数，
 * 以及设备句柄和初始化状态。
 */
typedef struct
{
    key_handler_ret_t (*pf_get_time_ms)(uint32_t      		      *);
} key_time_base_ms_t;

#ifdef OS_SUPPIRTING_KEY
/**
 * @brief KEY设备操作结构体
 *
 * 封装KEY外设的初始化、去初始化、启动和停止等操作函数，
 * 以及设备句柄和初始化状态。
 */
typedef struct
{
    key_handler_ret_t (*pf_os_delay_ms)(const              uint32_t);
} key_os_delay_ms_t;

/**
 * @brief KEY设备操作结构体
 *
 * 封装KEY外设的初始化、去初始化、启动和停止等操作函数，
 * 以及设备句柄和初始化状态。
 */
typedef struct
{
	/* 创建队列*/
    key_handler_ret_t (*pf_os_create_queue)(const uint32_t  itme_num,
										    const uint32_t itme_size,
										    void **            queue);
					
	/* 发送队列*/					    
    key_handler_ret_t (*pf_os_put_queue  )(void * const       queue,
										   void * const	 	    msg,
												 uint32_t  time_out);
										   
	/* 接收队列*/					    
    key_handler_ret_t (*pf_os_get_queue  )(void * const       queue,
										   void * const	 	    msg,
												 uint32_t  time_out);
										   
	/* 删除队列*/					    
    key_handler_ret_t (*pf_os_delet_queue)(void *             queue);
} key_os_queue_t;

/**
 * @brief KEY处理器输入参数结构体
 *
 * 封装KEY处理器初始化所需的配置参数，包括线程属性和系统接口。
 */
typedef struct
{
	/* 创建线程*/
    key_handler_ret_t (*pf_os_create_thread)( void * 			   pf_task,// 内部定义
										      const char * const task_name,// 外部定义
											  uint16_t		   stack_depth,// 外部定义
											  void * const task_parameters,// 内部定义
											  uint32_t 		 task_priority,// 外部定义
											  void *                thread );// 内部定义
	/* 删除线程*/
    key_handler_ret_t (*pf_os_delet_thread) ( void *           	   thread  );
}key_os_thread_t;

/**
 * @brief KEY按键读取函数指针类型
 *
 * 定义按键状态读取的函数接口，用于硬件抽象层实现。
 */
typedef struct
{
	/* 进入临界区*/
    key_handler_ret_t (*pf_os_critical_enter )				  (void);
   
	/* 退出临界区*/
    key_handler_ret_t (*pf_os_critical_exit  )				  (void);
} key_os_critical_t;
#endif

/**
 * @brief KEY按键注册函数指针类型
 *
 * 定义按键驱动注册的函数接口，用于设备管理。
 */
typedef struct
{
    void (*thread)(void *);
    char thread_name[24];
    uint16_t stack_depth;
    uint32_t priority;

    key_time_base_ms_t                  *	p_time_base_ms;
#ifdef OS_SUPPIRTING_KEY
    key_os_delay_ms_t                   *  p_os_time_delay;
    key_os_queue_t						*		p_os_queue;
    key_os_thread_t						*	   p_os_thread;
    key_os_critical_t					*	 p_os_critical;
#endif
} key_handler_input_t;

typedef struct bsp_key_handler bsp_key_handler_t;

/**
 * @brief DAC设备操作结构体
 *
 * 封装DAC外设的初始化、去初始化、启动和停止等操作函数，
 * 以及设备句柄和初始化状态。
 */
typedef key_handler_ret_t (*pf_key_read_t)(bsp_key_handler_t  *self);

/**
 * @brief DAC设备操作结构体
 *
 * 封装DAC外设的初始化、去初始化、启动和停止等操作函数，
 * 以及设备句柄和初始化状态。
 */
typedef key_handler_ret_t (*pf_key_register_t)(
                                           bsp_key_handler_t   *self,
                                           bsp_key_driver_t  *driver,
                                           key_index_t       * index);

/**
 * @brief DAC设备操作结构体
 *
 * 封装DAC外设的初始化、去初始化、启动和停止等操作函数，
 * 以及设备句柄和初始化状态。
 */
typedef struct bsp_key_handler
{
    /*******************Target of Internal Status*********/
    key_handler_init_t                         init_status;
	key_register_t						      key_instance;

    /*******************Target of Features****************/
	// 后续可用

    /*******************Target of IOs needed**************/
    /* The interface from Core layer			         */
    
    key_time_base_ms_t                  *	p_time_base_ms;
    /* The interface from OS   layer			         */
#ifdef OS_SUPPIRTING_KEY
    key_os_delay_ms_t                   *  p_os_time_delay;
    key_os_queue_t						*		p_os_queue;
    key_os_thread_t						*	   p_os_thread;
    key_os_critical_t					*	 p_os_critical;
    void			 					*     handle_queue;
    void 								*	 handle_thread;
#endif
	
    /*******************Target of APIs********************/
    pf_key_read_t                                 key_read;
	
	pf_key_register_t				  		  register_key;
}bsp_key_handler_t;

/**
 * @brief KEY处理器实例初始化函数
 *
 * 初始化KEY处理器实例，绑定硬件接口和系统函数，完成按键检测和事件处理的初始化。
 *
 * @param self KEY处理器实例指针
 * @param input KEY处理器输入参数结构体指针
 *
 * @return key_handler_ret_t 操作结果状态码
 * @retval KEY_HANDLER_RET_OK 初始化成功
 * @retval KEY_HANDLER_RET_ERROR 初始化失败
 */
key_handler_ret_t bsp_key_handler_inst(bsp_key_handler_t *self,
                                     key_handler_input_t *input);

#endif // END __RD0FF_BSP_KEY_HANDLER_H
